<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>readdir</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_007_1906">&nbsp;</a>NAME</h4><blockquote>
readdir, readdir_r - read directory
</blockquote><h4><a name = "tag_000_007_1907">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="systypes.h.html">sys/types.h</a>&gt;
#include &lt;<a href="dirent.h.html">dirent.h</a>&gt;

struct dirent *readdir(DIR *<i>dirp</i>);
int readdir_r(DIR *<i>dirp</i>, struct dirent *<i>entry</i>, struct dirent **<i>result</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_1908">&nbsp;</a>DESCRIPTION</h4><blockquote>
The type
<b>DIR</b>,
which is defined in the header
<i><a href="dirent.h.html">&lt;dirent.h&gt;</a></i>,
represents a
<i>directory stream</i>,
which is an ordered sequence of all the directory entries in a
particular directory.
Directory entries represent files; files may be removed from a
directory or added to a directory asynchronously to the operation of
<i>readdir()</i>.
<p>
The
<i>readdir()</i>
function returns a pointer to a structure representing the directory entry at
the current position in the directory stream specified by the argument
<i>dirp</i>,
and positions the directory stream at the next entry.
It returns a null pointer upon reaching the end of the directory stream.
The structure
<i>dirent</i>
defined by the
<i><a href="dirent.h.html">&lt;dirent.h&gt;</a></i>
header describes a directory entry.
<p>
If entries for dot or dot-dot exist, one entry will be returned
for dot and one entry will be returned for dot-dot; otherwise
they will not be returned.
<p>
The pointer returned by
<i>readdir()</i>
points to data which may be overwritten by another call to
<i>readdir()</i>
on the same directory stream.
This data is not overwritten by another call to
<i>readdir()</i>
on a different directory stream.
<p>
If a file is removed from or added to the directory after the most
recent call to
<i><a href="opendir.html">opendir()</a></i>
or
<i><a href="rewinddir.html">rewinddir()</a></i>,
whether a subsequent call to
<i>readdir()</i>
returns an entry for that file is unspecified.
<p>
The
<i>readdir()</i>
function may buffer several directory entries per actual read
operation;
<i>readdir()</i>
marks for update the
<i>st_atime</i>
field of the directory each time the directory is actually read.
<p>
After a call to
<i><a href="fork.html">fork()</a></i>,
either the parent or child (but not both) may continue processing
the directory stream using
<i>readdir()</i>,
<i><a href="rewinddir.html">rewinddir()</a></i>
or
<i><a href="seekdir.html">seekdir()</a></i>.
&nbsp;If both the parent and child processes use these functions, the result is
undefined.
<p>
If the entry names a symbolic link, the value of the
<b>d_ino</b>
member is unspecified.
<p>
The
<i>readdir()</i>
interface need not be reentrant.
<p>
The
<i>readdir_r()</i>
function initialises the
<b>dirent</b>
structure referenced by
<i>entry</i>
to represent the directory entry at the current position
in the directory stream referred to by
<i>dirp</i>,
store a pointer to this structure 
at the location referenced by
<i>result</i>,
and positions the directory stream at the next entry.
<p>
The storage pointed to by
<i>entry</i>
will be large enough for a
<b>dirent</b>
with an array of
<b>char</b>
<i>d_name</i>
member containing at least {NAME_MAX} plus one elements.
<p>
On successful return, the pointer returned at *<i>result</i>
will have the same value as the argument
<i>entry</i>.
Upon reaching the end of the directory stream,
this pointer will have the value NULL.
<p>
The
<i>readdir_r()</i>
function will not return directory entries containing empty names.
It is unspecified whether entries are returned for dot or dot-dot.
<p>
If a file is removed from or added to the directory
after the most recent call to
<i><a href="opendir.html">opendir()</a></i>
or
<i><a href="rewinddir.html">rewinddir()</a></i>,
whether a subsequent call to
<i>readdir_r()</i>
returns an entry for that file is unspecified.
<p>
The
<i>readdir_r()</i>
function may buffer several directory entries per actual read operation;
the
<i>readdir_r()</i>
function marks for update the
<i>st_atime</i>
field of the directory each time the directory is actually read.
<p>
Applications wishing to check for error situations should set
<i>errno</i>
to 0 before calling
<i>readdir()</i>.
If
<i>errno</i>
is set to non-zero on return, an error occurred.
</blockquote><h4><a name = "tag_000_007_1909">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>readdir()</i>
returns a pointer to an object of type
<b>struct dirent</b>.
When an error is encountered, a null pointer is returned and
<i>errno</i>
is set to indicate the error.  When the end of the directory is encountered, a
null pointer is returned and
<i>errno</i>
is not changed.
<p>
If successful, the
<i>readdir_r()</i>
function returns zero.
Otherwise, an error number is returned to indicate the error.
</blockquote><h4><a name = "tag_000_007_1910">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>readdir()</i>
function will fail if:
<dl compact>

<dt>[EOVERFLOW]<dd>
One of the values in the structure to be returned cannot be
represented correctly.

</dl>
<p>
The
<i>readdir()</i>
function may fail if:
<dl compact>

<dt>[EBADF]<dd>
The
<i>dirp</i>
argument does not refer to an open directory stream.

<dt>[ENOENT]<dd>
The current position of the directory stream is invalid.

</dl>
<p>
The 
<i>readdir_r()</i>
function may fail if:
<dl compact>

<dt>[EBADF]<dd>
The
<i>dirp</i>
argument does not refer to an open directory stream.

</dl>
</blockquote><h4><a name = "tag_000_007_1911">&nbsp;</a>EXAMPLES</h4><blockquote>
The following sample code will search the current directory for the
entry
<i>name</i>:
<pre>
<code>
dirp = opendir(".");

while (dirp) {
    errno = 0;
    if ((dp = readdir(dirp)) != NULL) {
        if (strcmp(dp-&gt;d_name, name) == 0) {
            closedir(dirp);
            return FOUND;
        }
    } else {
        if (errno == 0) {
            closedir(dirp);
            return NOT_FOUND;
        }
        closedir(dirp);
        return READ_ERROR;
    }
}

return OPEN_ERROR;
</code>
</pre>
</blockquote><h4><a name = "tag_000_007_1912">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The
<i>readdir()</i>
function should be used in conjunction with
<i><a href="opendir.html">opendir()</a></i>,
<i><a href="closedir.html">closedir()</a></i>
and
<i><a href="rewinddir.html">rewinddir()</a></i>
to examine the contents of the directory.
</blockquote><h4><a name = "tag_000_007_1913">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_007_1914">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="closedir.html">closedir()</a></i>,
<i><a href="lstat.html">lstat()</a></i>,
<i><a href="opendir.html">opendir()</a></i>,
<i><a href="rewinddir.html">rewinddir()</a></i>,
<i><a href="symlink.html">symlink()</a></i>,
<i><a href="dirent.h.html">&lt;dirent.h&gt;</a></i>,
<i><a href="systypes.h.html">&lt;sys/types.h&gt;</a></i>.
</blockquote><h4>DERIVATION</h4><blockquote>
<i>readdir_r()</i> derived from the POSIX Threads Extension (1003.1c-1995).
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
